Scenario #9610: A Global Admin Can Create an Api Key Subject with Global Admin Role

UseCase Create Api Key Subject With Global Admin Role => ApiKey-Subject: master.key

API_KEY subjects authenticate technical clients via the Hostsharing-Api-Key HTTP header instead of a Keycloak OIDC JWT, e.g. automation programs, completely bypassing Keycloak. Only a global-admin may create API_KEY subjects. The clear-text API-key is returned only once, in the response of creating the API_KEY subject; just its hash gets stored. Like GROUP subjects, API_KEY subjects cannot have an account. Global API_KEY subjects do not belong to a realm, thus their name must neither contain a - (the realm-prefix delimiter) nor a / (the GROUP subject marker).

Properties

Given

name	value
subjectUuid	a91c0001-0000-0000-0000-000000000001
subjectName	master.key

Create the API_KEY Subject

The response contains the generated clear-text API-key (property apiKey) exactly once; it cannot be retrieved again.

HTTP POST "/api/rbac/subjects" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }` \
  <<EOF
{
  "uuid" : "a91c0001-0000-0000-0000-000000000001",
  "name" : "master.key",
  "type" : "API_KEY"
}
EOF
=> status: 201 CREATED a91c0001-0000-0000-0000-000000000001
{
  "uuid" : "a91c0001-0000-0000-0000-000000000001",
  "name" : "master.key",
  "organization" : "master",
  "type" : "API_KEY",
  "apiKey" : "hsak_master.key.80255e030a8da5ccd79c2af2ba5f5d7d73c8a0c9268d545344bac2210d828e52",
  "scopes" : null,
  "expiresAt" : null
}

Prerequisite: Resolve the UUID of the global ADMIN role

The grant API needs the UUID of the role which we want to grant.

HTTP GET "/api/rbac/roles?name=rbac.global%23global%3AADMIN" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }`
=> status: 200 OK 
[ {
  "uuid" : "589a6260-757d-4e3e-a2b7-08ca8b758868",
  "object.uuid" : "9b7b3d20-a88f-4c19-8bc7-efdb8dd24832",
  "objectTable" : "rbac.global",
  "objectIdName" : "global",
  "roleType" : "ADMIN",
  "roleName" : "rbac.global#9b7b3d20-a88f-4c19-8bc7-efdb8dd24832:ADMIN",
  "roleIdName" : "rbac.global#global:ADMIN"
} ]

Grant the global ADMIN role to the API_KEY Subject

HTTP POST "/api/rbac/grants" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }` \
  -H 'Hostsharing-Assumed-Roles: rbac.global#global:ADMIN' \
  <<EOF
{
  "assumed" : true,
  "grantedRole.uuid" : "589a6260-757d-4e3e-a2b7-08ca8b758868", // globalAdminRoleUuidToGrant
  "granteeSubject.uuid" : "a91c0001-0000-0000-0000-000000000001"
}
EOF
=> status: 201 CREATED 589a6260-757d-4e3e-a2b7-08ca8b758868 // globalAdminRoleUuidToGrant

Verify the API-key authenticates as its Subject with the global-admin role, without any JWT

HTTP GET "/api/hs/accounts/current" \
  -H "Hostsharing-Api-Key: $HSADMINNG_API_KEY"
=> status: 200 OK 
{
  "subject" : {
    "uuid" : "a91c0001-0000-0000-0000-000000000001",
    "name" : "master.key",
    "organization" : "master",
    "type" : "API_KEY"
  },
  "person" : null,
  "globalAdmin" : true
}

---

generated on 2026-08-10 03:08:45 for branch HEAD